Scenario #9610: A Global Admin Can Create an Api Key Subject with Global Admin Role

UseCase Create Api Key Subject With Global Admin Role => ApiKey-Subject: master.key

API_KEY subjects authenticate technical clients via the Hostsharing-Api-Key HTTP header instead of a Keycloak OIDC JWT, e.g. automation programs, completely bypassing Keycloak. Only a global-admin may create API_KEY subjects. The clear-text API-key is returned only once, in the response of creating the API_KEY subject; just its hash gets stored. Like GROUP subjects, API_KEY subjects cannot have an account. Global API_KEY subjects do not belong to a realm, thus their name must neither contain a - (the realm-prefix delimiter) nor a / (the GROUP subject marker).

Properties

Given

name	value
subjectUuid	a91c0001-0000-0000-0000-000000000001
subjectName	master.key

Create the API_KEY Subject

The response contains the generated clear-text API-key (property apiKey) exactly once; it cannot be retrieved again.

HTTP POST "/api/rbac/subjects" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  <<EOF
{
  "uuid" : "a91c0001-0000-0000-0000-000000000001",
  "name" : "master.key",
  "type" : "API_KEY"
}
EOF
=> status: 201 CREATED a91c0001-0000-0000-0000-000000000001
{
  "uuid" : "a91c0001-0000-0000-0000-000000000001",
  "name" : "master.key",
  "organization" : "master",
  "type" : "API_KEY",
  "apiKey" : "hsak_master.key.9dd412ccb2f9f9bf38d5c636e5d4d7e04473f2c9034fb6254bca7c185f4bc489",
  "scopes" : null,
  "expiresAt" : null
}

Prerequisite: Resolve the UUID of the global ADMIN role

The grant API needs the UUID of the role which we want to grant.

HTTP GET "/api/rbac/roles?name=rbac.global%23global%3AADMIN" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }`
=> status: 200 OK 
[ {
  "uuid" : "7ea7e6cb-16dd-4fb9-aa82-427df5f205d7",
  "object.uuid" : "6ec9aacc-2bd3-4678-a8f9-31e61eef3b0a",
  "objectTable" : "rbac.global",
  "objectIdName" : "global",
  "roleType" : "ADMIN",
  "roleName" : "rbac.global#6ec9aacc-2bd3-4678-a8f9-31e61eef3b0a:ADMIN",
  "roleIdName" : "rbac.global#global:ADMIN"
} ]

Grant the global ADMIN role to the API_KEY Subject

HTTP POST "/api/rbac/grants" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  -H 'Hostsharing-Assumed-Roles: rbac.global#global:ADMIN' \
  <<EOF
{
  "assumed" : true,
  "grantedRole.uuid" : "7ea7e6cb-16dd-4fb9-aa82-427df5f205d7", // globalAdminRoleUuidToGrant
  "granteeSubject.uuid" : "a91c0001-0000-0000-0000-000000000001"
}
EOF
=> status: 201 CREATED 7ea7e6cb-16dd-4fb9-aa82-427df5f205d7 // globalAdminRoleUuidToGrant

Verify the API-key authenticates as its Subject with the global-admin role, without any JWT

HTTP GET "/api/hs/accounts/current" \
  -H "Hostsharing-Api-Key: $HSADMINNG_API_KEY"
=> status: 200 OK 
{
  "subject" : {
    "uuid" : "a91c0001-0000-0000-0000-000000000001",
    "name" : "master.key",
    "organization" : "master",
    "type" : "API_KEY"
  },
  "person" : null,
  "globalAdmin" : true
}

---

generated on 2026-08-10 01:38:05 for branch